home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d886.lha / PatchLibrary / Patch.doc < prev    next >
Text File  |  1993-07-16  |  7KB  |  232 lines
  1. TABLE OF CONTENTS
  2.  
  3. patch.library/FindPatch
  4. patch.library/InstallPatch
  5. patch.library/RemovePatch
  6. patch.library/WaitRemovePatch
  7.  
  8.  
  9.  patch.library/InstallPatch
  10.  
  11.     NAME
  12.     InstallPatch -- Installs a patchroutine for libraryfunctions.
  13.  
  14.     SYNOPSIS
  15.     Patch = InstallPatch( NewPatch )
  16.     D0               A0
  17.  
  18.     struct Patch *InstallPatch( struct NewPatch * );
  19.  
  20.     FUNCTION
  21.     Opens a library and installs a user provided routine to a library
  22.     function.
  23.  
  24.     Before you call InstallPatch(), you must initialize an instance of
  25.     a NewPatch structure.  NewPatch is a structure that contains
  26.     all of the arguments needed to install a patch.  The NewPatch
  27.     structure may be discarded immediately after it is used to install
  28.     the patch.
  29.  
  30.     INPUTS
  31.     NewPatch = pointer to an instance of a NewPatch structure
  32.                containing the following fields
  33.  
  34.         NPAT_NewCode:
  35.             Pointer to the patch code to be installed.
  36.             If NPAT_PRI is >= 0 then your patch code gets all
  37.             registers set to the same values as the program
  38.             that called the function.
  39.             If NPAT_PRI is < 0 then your patch code gets all
  40.             registers set to the same values as the library
  41.             function returned them.
  42.             It is up to the patch code to keep the registers
  43.             intact, when it returns with 'rts'.
  44.             Due to the internal implementation of the patches,
  45.             library functions patched with patch.library
  46.             require four bytes more stack.  This might cause in
  47.             very rare cases crashes due to stack overflow.
  48.         NPAT_NewCodeSize:
  49.             Optional length of the patch code to be installed.
  50.             If this field is set to the correct value
  51.             the PC-RELATIVE patch code starting at NPAT_NewCode
  52.             will be copied to an internal Buffer.
  53.             So it is possible to deallocate the patch code
  54.             after InstallPatch returns.
  55.         NPAT_LibraryName:
  56.             Pointer to the name of the library, which contains
  57.             the function to patch.
  58.             ( as in exec.library/OpenLibrary() )
  59.         NPAT_LibVersion:
  60.             version of the Library to open should be specified,
  61.             if a function is available only from a certain
  62.             library version on.
  63.             ( as in exec.library/OpenLibrary() )
  64.         NPAT_LVO:
  65.             Library Offset Vector (LVO) of the function to patch
  66.         NPAT_Priority:
  67.             Priority of the patch
  68.             valid range: -127...+126
  69.             It indicates the sequence of patches, if
  70.             more than one patch for a function is installed.
  71.             The original code has a priority of 0.
  72.             Priority:    Meaning:
  73.             >0: patch will be executed before the original
  74.             <0: patch will be executed after the original
  75.             =0: patch will be executed instead of the original
  76.         NPAT_Flags:
  77.             No flags are used and this field will be ignored
  78.             ( keep zero )
  79.         NPAT_PatchName:
  80.             An optional pointer to a string, which can be used
  81.             to search for a patch with FindPatch().
  82.             The null-terminated string will be copied, so you
  83.             may free its memory when InstallPatch() returns.
  84.             The string should contain the name of your program
  85.             to identify the program that installed the task.
  86.         NPAT_Result2:
  87.             An optional pointer to a longword, which will contain
  88.             an errorcode as defined later. Assembler programmers
  89.             can always find this in d1, too.
  90.  
  91.     RESULT
  92.         Patch = pointer to a patch structure or NULL on failure
  93.              This structure is totally PRIVATE, so hands off.
  94.  
  95.     NOTES
  96.  
  97.     BUGS
  98.  
  99.     SEE ALSO
  100.     WaitRemovePatch(), RemovePatch(), Patch.h,
  101.     exec.library/OpenLibrary()
  102.  
  103.  
  104.  patch.library/WaitRemovePatch
  105.  
  106.     NAME
  107.     WaitRemovePatch -- Waits until it is possible to remove a patch.
  108.  
  109.     SYNOPSIS
  110.     Error = WaitRemovePatch( Patch )
  111.     D0                 A0
  112.  
  113.     ULONG Error WaitRemovePatch( struct Patch * );
  114.  
  115.     FUNCTION
  116.     Waits until no task is using the library function.
  117.     Then RemovePatch() will be called to remove the patch.
  118.  
  119.     All allocated resources for that specific patch will
  120.     be deallocated.
  121.  
  122.     INPUTS
  123.     Patch = pointer to the PRIVATE patch structure or NULL for no action
  124.  
  125.     RESULT
  126.         Error = Errorcodes as defined in Patch.h.
  127.             All errorcodes as from RemovePatch() except
  128.             PATERR_PatchInUse are possible.
  129.  
  130.     NOTES
  131.     Removing a patch routine can never be made absolutely save.
  132.     Although patch.library does anything possible to provide methods
  133.     to minimize the chance of a crash, there will always be a
  134.     slight chance.
  135.     So minimize the number of install and remove operations.
  136.  
  137.     BUGS
  138.  
  139.     SEE ALSO
  140.     RemovePatch(), Patch.h
  141.  
  142.  
  143.  patch.library/RemovePatch
  144.  
  145.     NAME
  146.     RemovePatch -- Removes a patch installed by InstallPatch().
  147.  
  148.     SYNOPSIS
  149.     Error = RemovePatch( Patch )
  150.     D0                 A0
  151.  
  152.     ULONG Error RemovePatch( struct Patch * );
  153.  
  154.     FUNCTION
  155.     Removes a patch from a library function.
  156.  
  157.     All allocated resources for that specific patch will
  158.     be deallocated.
  159.  
  160.     INPUTS
  161.     Patch = pointer to the PRIVATE patch structure or NULL for no action
  162.  
  163.     RESULT
  164.         Error = Errorcodes as defined in Patch.h.
  165.         PATERR_Ok
  166.             Indicates success of the operation.
  167.         PATERR_PatchInUse
  168.             Indicates that some other task is using the
  169.             installed function and can't be removed now.
  170.             Your task may wait and try again later.
  171.         PATERR_PatchInstalled
  172.             Indicates that a patchcode has been installed for
  173.             that function after your patch.library patch has
  174.             been installed and your patch is the only
  175.             patch.library patch for that function.
  176.             If patch.library would remove your patch
  177.             tasks would jump into deallocated memory
  178.             Result:  blinking borders.
  179.         PATERR_InvalidHandle
  180.             Indicates that the pointer you passed to
  181.             RemovePatch() was not or no longer valid.
  182.             This might happen, if you pass a wrong pointer or
  183.             you got the pointer via FindPatch() and another
  184.             task has removed the patch before this task called
  185.             RemovePatch().
  186.  
  187.     NOTES
  188.     Removing a patch routine can never be made absolutely save.
  189.     Although patch.library does anything possible to provide methods
  190.     to minimize the chance of a crash, there will always be a
  191.     slight chance.
  192.     So minimize the number of install and remove operations.
  193.  
  194.     BUGS
  195.  
  196.     SEE ALSO
  197.     WaitRemovePatch(), Patch.h
  198.  
  199.  
  200.  patch.library/FindPatch
  201.  
  202.     NAME
  203.     FindPatch -- find a patch structure with a given name.
  204.  
  205.     SYNOPSIS
  206.     Patch = FindPatch( Name )
  207.     D0           A0
  208.  
  209.     struct Patch *FindPatch( STRPTR );
  210.  
  211.     FUNCTION
  212.     This function will search the patch.library private lists for a
  213.     patch structure with the given name. The first patch matching
  214.     this name will be returned.
  215.  
  216.     INPUTS
  217.     Name = Name of the patch structure to find
  218.  
  219.     RESULT
  220.     Patch = a pointer to the patch structure with the same name else
  221.         zero to indicate that the string was not found.
  222.  
  223.     NOTES
  224.     If your task is not the owner of the patch, the
  225.     pointer is only valid as long as the system is in forbid.
  226.  
  227.     BUGS
  228.  
  229.     SEE ALSO
  230.     WaitRemovePatch(), RemovePatch(), Patch.h
  231.  
  232.